amd64/bareMetalOS-0.5.2/baremetal0.5.2/docs/3 - BareMetal OS - System Calls.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
   2 <html lang="en">
   3
   4 <head>
   5 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   6 <title>BareMetal OS - System Calls</title>
   7 <style type="text/css">
   8 body {color:#222; font-family:Verdana,sans-serif; font-size:12px;}
   9 pre {background-color:#FAFAFA; border:1px solid #DADADA; margin-bottom:6px; padding:6px;}
  10 </style>
  11 <script type="text/javascript" src="scripts/shCore.js"></script>
  12 <script type="text/javascript" src="scripts/shBrushAsm.js"></script>
  13 <script type="text/javascript" src="scripts/shBrushCpp.js"></script>
  14 <link type="text/css" rel="stylesheet" href="css/shCore.css"/>
  15 <link type="text/css" rel="stylesheet" href="css/shThemeDefault.css"/>
  16 <script type="text/javascript">
  17         SyntaxHighlighter.defaults['tab-size'] = 8;
  18         SyntaxHighlighter.all();
  19 </script>
  20 </head>
  21
  22 <body>
  23 <div class="container">
  24
  25 <h1>BareMetal OS - System Calls</h1>
  26
  27 <h3>Version 0.5.2 (DRAFT), 4 July 2011 - Return Infinity</h3>
  28
  29 <p>This documentation details the system calls provided by BareMetal and how applications can use them.</p>
  30
  31 <br />
  32
  33
  34 <hr noshade="noshade"></hr>
  35
  36
  37 <h2>System Calls</h2>
  38
  39 <h3>Introduction</h3>
  40
  41 <p>The BareMetal OS kernel includes system calls for outputting to the screen, taking keyboard input, manipulating strings, producing PC speaker sounds, math operations and disk I/O. You can get a quick reference to the registers that these calls take and pass back by looking at <strong>bmdev.asm</strong>, and see practical use of the calls in the <strong>programs/</strong> directory.</p>
  42
  43 <p>Here we have a detailed API explanation with examples. You can see the full source code behind these system calls in the <strong>os/syscalls/</strong> directory in BareMetal OS. Each aspect of the API below is contained within their respective assembly source files.</p>
  44
  45 <a name="top"></a>
  46 <h3>Table of contents</h3>
  47 <ol>
  48 <li><a href="#debug">Debug</a></li>
  49 <li><a href="#file">File I/O</a></li>
  50 <li><a href="#input">Input</a></li>
  51 <li><a href="#math">Mathematics</a></li>
  52 <li><a href="#memory">Memory</a></li>
  53 <li><a href="#misc">Miscellaneous</a></li>
  54 <li><a href="#network">Networking</a></li>
  55 <li><a href="#output">Output</a></li>
  56 <li><a href="#serial">Serial</a></li>
  57 <li><a href="#smp">SMP (Symmetric Multiprocessing)</a></li>
  58 <li><a href="#sound">Sound</a></li>
  59 <li><a href="#string">String</a></li>
  60 </ol>
  61 <br />
  62
  63
  64
  65
  66
  67 <hr noshade="noshade" style="width:80%;"></hr>
  68 <a name="debug"></a>
  69 <h2>Debug</h2>
  70 <p></p>
  71
  72
  73
  74 <h3>b_debug_dump_reg</h3>
  75 <p><strong>Dump the values on the registers to the screen</strong></p>
  76 <pre>
  77  IN:    Nothing
  78 OUT:    Nothing, all registers preserved
  79 </pre>
  80 <p>Example:</p>
  81 <pre class="brush: asm; tab-size: 8">
  82         call b_debug_dump_reg
  83 </pre>
  84 <br />
  85
  86
  87
  88 <h3>b_debug_dump_mem</h3>
  89 <p><strong>Dump some memory content to the screen</strong></p>
  90 <pre>
  91  IN:    RSI = Start of memory address to dump
  92         RCX = number of bytes to dump
  93 OUT:    Nothing, all registers preserved
  94 </pre>
  95 <p>Example:</p>
  96 <pre class="brush: asm; tab-size: 8">
  97         mov rsi, 0x1000         ; Dump starting at this memory address
  98         mov rcx, 100            ; Display 100 bytes
  99         call b_debug_dump_mem
 100 </pre>
 101 <br />
 102
 103
 104
 105 <h3>b_debug_dump_rax|eax|ax|al</h3>
 106 <p><strong>Dump content of RAX, EAX, AX, or AL to the screen in hex format</strong></p>
 107 <pre>
 108  IN:    RAX|EAX|AX|AL = content to dump
 109 OUT:    Nothing, all registers preserved
 110 </pre>
 111 <p>Example:</p>
 112 <pre class="brush: asm; tab-size: 8">
 113         call b_debug_dump_rax           ; Dump the entire 64-bit register
 114         call b_debug_dump_eax           ; Dump only the lower 32-bits
 115         call b_debug_dump_ax            ; Dump only the lower 16-bits
 116         call b_debug_dump_al            ; Dump only the lower 8-bits
 117 </pre>
 118 <br />
 119
 120
 121
 122 <h3>b_debug_get_ip</h3>
 123 <p><strong>Dump content of RIP into RAX</strong></p>
 124 <pre>
 125  IN:    Nothing
 126 OUT:    RAX = RIP
 127 </pre>
 128 <p>This function is useful for retreiving the Instruction Pointer at the time b_debug_get_ip was called.</p>
 129 <p>Example:</p>
 130 <pre class="brush: asm; tab-size: 8">
 131         call b_debug_get_ip
 132 </pre>
 133 <br />
 134
 135
 136
 137
 138
 139 <hr noshade="noshade" style="width:80%;"></hr>
 140 <a name="file"></a>
 141 <h2>File I/O - Functions for dealing with files</h2>
 142 <p></p>
 143
 144
 145
 146 <h3>b_file_read</h3>
 147 <p><strong>Read a file from disk into memory</strong></p>
 148 <pre>
 149  IN:    RSI = Address of filename string
 150         RDI = Memory location where file will be loaded to
 151 OUT:    Carry is set if the file was not found or an error occured
 152 </pre>
 153 <p></p>
 154 <p>Example:</p>
 155 <pre class="brush: asm; tab-size: 8">
 156         mov rsi, testfile       ; File name
 157         mov rdi, 0x1000000      ; Read file to this memory address
 158         call b_file_read
 159         jnc fileok              ; If carry is clear then no error occured
 160
 161         ... error handling here ...
 162
 163 fileok:
 164         ... work with file ...
 165
 166         testfile: db "test.txt", 0
 167 </pre>
 168 <br />
 169
 170
 171
 172 <h3>b_file_write</h3>
 173 <p><strong>Write memory to a file on disk</strong></p>
 174 <pre>
 175  IN:    RSI = Memory location of data to be written
 176         RDI = Address of filename string
 177         RCX = Number of bytes to write
 178 OUT:    Carry is set if an error occured
 179 </pre>
 180 <p></p>
 181 <p>Example:</p>
 182 <pre class="brush: asm; tab-size: 8">
 183         mov rdi, testfile       ; File name
 184         mov rsi, 0x100A000      ; Data to write is at this memory address
 185         mov rcx, 50             ; Write 50 bytes
 186         call b_file_write
 187         jnc fileok              ; If carry is clear then no error occured
 188
 189         ... error handling here ...
 190
 191 fileok:
 192         ... continue on ...
 193
 194         testfile: db "test.txt", 0
 195 </pre>
 196 <br />
 197
 198
 199
 200 <h3>b_file_delete</h3>
 201 <p><strong>Delete a file from disk</strong></p>
 202 <pre>
 203  IN:    RSI = Memory location of file name to delete
 204 OUT:    Carry is set if the file was not found or an error occured
 205 </pre>
 206 <p></p>
 207 <p>Example:</p>
 208 <pre class="brush: asm; tab-size: 8">
 209         mov rsi, testfile       ; Name of file to delete
 210         call b_file_delete
 211
 212         ...
 213
 214         testfile: db "deleteme.txt", 0
 215 </pre>
 216 <br />
 217
 218
 219
 220 <h3>b_file_get_list</h3>
 221 <p><strong>Generate a list of files on disk</strong></p>
 222 <pre>
 223  IN:    RDI = location to store list
 224 OUT:    RDI = pointer to end of list
 225 </pre>
 226 <p></p>
 227 <p>Example:</p>
 228 <pre class="brush: asm; tab-size: 8">
 229         mov rdi, temp_string            ; Our temporary string
 230         mov rsi, rdi                    ; Point RSI to the start of the string
 231         call b_file_get_list
 232         call b_print_string             ; Print the directory listing
 233 </pre>
 234 <br />
 235
 236
 237
 238 <h3>b_file_get_size</h3>
 239 <p><strong>Return the size of a file on disk</strong></p>
 240 <pre>
 241  IN:    RSI = Address of filename string
 242 OUT:    RCX = Size in bytes
 243         Carry is set if the file was not found or an error occured
 244 </pre>
 245 <p></p>
 246 <p>Example:</p>
 247 <pre class="brush: asm; tab-size: 8">
 248         mov rsi, temp_string            ; Our temporary name string
 249         call b_file_get_size
 250         jc namenotfound
 251 </pre>
 252 <br />
 253
 254
 255
 256
 257
 258 <hr noshade="noshade" style="width:80%;"></hr>
 259 <a name="input"></a>
 260 <h2>Input - Functions for dealing with input from the keyboard</h2>
 261 <p></p>
 262
 263
 264
 265 <h3>b_input_key_check</h3>
 266 <p><strong>Scans keyboard for input, but doesn't wait</strong></p>
 267 <pre>
 268  IN:    Nothing
 269 OUT:    AL = 0 if no key pressed, otherwise ASCII code, other regs preserved
 270         Carry flag is set if there was a keystoke, clear if there was not
 271         All other registers preserved
 272 </pre>
 273 <p>Example:</p>
 274 <pre class="brush: asm; tab-size: 8">
 275         call b_input_key_check
 276         jnc nokeypressed                ; If carry is not set than no key was pressed
 277         call b_print_char               ; Print the character that was pressed
 278
 279         ...
 280
 281         nokeypressed:
 282 </pre>
 283 <br />
 284
 285
 286
 287 <h3>b_input_key_wait</h3>
 288 <p><strong>Waits for keypress and returns key</strong></p>
 289 <pre>
 290  IN:    Nothing
 291 OUT:    AL = key pressed
 292         All other registers preserved
 293 </pre>
 294 <p>Example:</p>
 295 <pre class="brush: asm; tab-size: 8">
 296         call b_input_key_wait
 297         cmp al, 'q'             ; Check if Q key was hit
 298         je gottheletterq
 299         cmp al, 'w'             ; Check if W key was hit
 300         je gottheletterw
 301
 302         ...
 303
 304         gottheletterq:
 305 </pre>
 306 <br />
 307
 308
 309
 310 <h3>b_input_string</h3>
 311 <p><strong>Take string from keyboard entry</strong></p>
 312 <pre>
 313  IN:    RDI = location where string will be stored
 314         RCX = number of characters to accept
 315 OUT:    RCX = length of string that was inputed (NULL not counted)
 316         All other registers preserved
 317 </pre>
 318 <p>Make sure that RCX is set to a sane value as it will stop memory from being corrupted.</p>
 319 <p>Example:</p>
 320 <pre class="brush: asm; tab-size: 8">
 321         mov rdi, inputstring
 322         mov rcx, 10
 323         call b_input_string
 324
 325         ...
 326
 327         inputstring: times 11 db 0
 328 </pre>
 329 <br />
 330
 331
 332
 333
 334
 335 <hr noshade="noshade" style="width:80%;"></hr>
 336 <a name="math"></a>
 337 <h2>Mathematics</h2>
 338 <p></p>
 339
 340
 341
 342 <h3>b_oword_add</h3>
 343 <p><strong>Add two 128-bit integer together</strong></p>
 344 <pre>
 345  IN:    RDX,RAX = Integer 1, RCX,RBX = Integer 2
 346 OUT:    RDX,RAX = Result
 347         Carry set if overflow
 348 </pre>
 349 <p>Example:</p>
 350 <pre class="brush: asm; tab-size: 8">
 351
 352 </pre>
 353 <br />
 354
 355
 356
 357
 358
 359 <hr noshade="noshade" style="width:80%;"></hr>
 360 <a name="memory"></a>
 361 <h2>Memory</h2>
 362 <p></p>
 363
 364
 365
 366 <h3>b_mem_allocate</h3>
 367 <p><strong>Allocates the requested number of 2 MiB pages</strong></p>
 368 <pre>
 369  IN:    RCX = Number of pages to allocate
 370 OUT:    RAX = Starting address
 371         RCX = Number of pages allocated (Set to the value asked for or 0 on failure)
 372 </pre>
 373 This function will only allocate continous pages
 374 <p>Example:</p>
 375 <pre class="brush: asm; tab-size: 8">
 376         mov rcx, 4              ; Try to allocate 4 pages (8 MiB)
 377         call b_mem_allocate
 378         cmp rcx, 0
 379         je fail
 380         mov [mempointer], rax   ; Save the pointer
 381
 382         ...
 383
 384         fail:
 385 </pre>
 386 <br />
 387
 388
 389
 390 <h3>b_mem_release</h3>
 391 <p><strong>Frees the requested number of 2 MiB pages</strong></p>
 392 <pre>
 393  IN:    RAX = Starting address
 394         RCX = Number of pages to free
 395 OUT:    RCX = Number of pages freed
 396 </pre>
 397 <p>Example:</p>
 398 <pre class="brush: asm; tab-size: 8">
 399         mov rax, [mempointer]   ; Restore the pointer
 400         mov rcx, 4              ; Free 4 pages (8 MiB)
 401         call b_mem_release
 402 </pre>
 403 <br />
 404
 405
 406
 407 <h3>b_mem_get_free</h3>
 408 <p><strong>Returns the number of 2 MiB pages that are available</strong></p>
 409 <pre>
 410  IN:    Nothing
 411 OUT:    RCX = Number of free 2 MiB pages
 412 </pre>
 413 <p>Example:</p>
 414 <pre class="brush: asm; tab-size: 8">
 415         call b_mem_get_free
 416 </pre>
 417 <br />
 418
 419
 420
 421
 422
 423 <hr noshade="noshade" style="width:80%;"></hr>
 424 <a name="misc"></a>
 425 <h2>Misc</h2>
 426 <p></p>
 427
 428
 429
 430 <h3>b_delay</h3>
 431 <p><strong>Delay by X</strong></p>
 432 <pre>
 433  IN:    RCX = Time in eights of a second
 434 OUT:    All registers preserved
 435 </pre>
 436 <p>A value of 8 in RCX will delay 1 second and a value of 1 will delay 1/8 of a second. This function depends on the RTC (IRQ 8) so interrupts must be enabled.</p>
 437 <p>Example:</p>
 438 <pre class="brush: asm; tab-size: 8">
 439         mov rcx, 16
 440         call b_delay            ; Pause for 2 seconds
 441 </pre>
 442 <br />
 443
 444
 445
 446
 447
 448 <hr noshade="noshade" style="width:80%;"></hr>
 449 <a name="network"></a>
 450 <h2>Networking</h2>
 451 <p></p>
 452
 453
 454
 455 <h3>b_ethernet_avail</h3>
 456 <p><strong>Check if Ethernet is available</strong></p>
 457 <pre>
 458  IN:    Nothing.
 459 OUT:    RAX = MAC Address if Ethernet is enabled, otherwise 0. All other registers preserved
 460 </pre>
 461 <p>Example:</p>
 462 <pre class="brush: asm; tab-size: 8">
 463         call b_ethernet_avail
 464         cmp rax, 0
 465         je noEthernet
 466 </pre>
 467 <br />
 468
 469
 470
 471 <h3>b_ethernet_tx</h3>
 472 <p><strong>Transmit a packet via Ethernet</strong></p>
 473 <pre>
 474  IN:    RSI = Memory location where data is stored
 475         RDI = Pointer to 48 bit destination address
 476         BX = Type of packet (If set to 0 then the EtherType will be set to the length of data)
 477         CX = Length of data
 478 OUT:    Nothing. All registers preserved
 479 </pre>
 480 <p>Example:</p>
 481 <pre class="brush: asm; tab-size: 8">
 482         mov rsi, datalocation
 483         mov rdi, peeraddress
 484         mov rbx, 0xBAAB
 485         mov rcx, 63
 486         call b_ethernet_tx
 487 </pre>
 488 <br />
 489
 490
 491
 492 <h3>b_ethernet_rx</h3>
 493 <p><strong>Polls the Ethernet card for received data</strong></p>
 494 <pre>
 495  IN:    RDI = Memory location where packet will be stored
 496 OUT:    RCX = Length of packet
 497         All other registers preserved
 498 </pre>
 499 <p>Example:</p>
 500 <pre class="brush: asm; tab-size: 8">
 501         mov rdi, EthernetBuffer
 502         call b_ethernet_rx
 503         cmp rcx, 0
 504         je nopacket
 505 </pre>
 506 <br />
 507
 508
 509
 510
 511
 512 <hr noshade="noshade" style="width:80%;"></hr>
 513 <a name="output"></a>
 514 <h2>Output - Functions for dealing with output to the screen</h2>
 515 <p></p>
 516
 517
 518
 519 <h3>b_move_cursor</h3>
 520 <p><strong>Moves cursor in text mode</strong></p>
 521 <pre>
 522  IN:    AH  = row
 523         AL  = column
 524 OUT:    All registers preserved
 525 </pre>
 526 <p>In normal text mode the screen is 80x25. First row and column are both 0. Max row is 24 and max column is 79.</p>
 527 <p>Example:</p>
 528 <pre class="brush: asm; tab-size: 8">
 529         mov al, 5
 530         mov ah, 5
 531         call b_move_cursor      ; Move cursor to (5,5)
 532
 533         ...
 534
 535         mov ax, 0x0505
 536         call b_move_cursor      ; Same as above but we set AL and AH at the same time
 537 </pre>
 538 <br />
 539
 540
 541
 542 <h3>b_inc_cursor</h3>
 543 <p><strong>Increment the hardware cursor by one</strong></p>
 544 <pre>
 545  IN:    Nothing
 546 OUT:    All registers preserved
 547 </pre>
 548 <p>This function will automatically call b_scroll_screen if required.</p>
 549 <p>Example:</p>
 550 <pre class="brush: asm; tab-size: 8">
 551         call b_inc_cursor
 552 </pre>
 553 <br />
 554
 555
 556
 557 <h3>b_dec_cursor</h3>
 558 <p><strong>Decrement the hardware cursor by one</strong></p>
 559 <pre>
 560  IN:    Nothing
 561 OUT:    All registers preserved
 562 </pre>
 563 <p>Example:</p>
 564 <pre class="brush: asm; tab-size: 8">
 565         call b_dec_cursor
 566 </pre>
 567 <br />
 568
 569
 570
 571 <h3>b_print_newline</h3>
 572 <p><strong>Reset cursor to start of next line and scroll if needed</strong></p>
 573 <pre>
 574  IN:    Nothing
 575 OUT:    All registers perserved
 576 </pre>
 577 <p>Example:</p>
 578 <pre class="brush: asm; tab-size: 8">
 579         call b_print_newline
 580 </pre>
 581 <br />
 582
 583
 584
 585 <h3>b_print_string</h3>
 586 <p><strong>Displays text</strong></p>
 587 <pre>
 588  IN:    RSI = message location (zero-terminated string)
 589 OUT:    All registers perserved
 590 </pre>
 591 <p>This function defaults to Light Gray text on a Black background</p>
 592 <p>Example:</p>
 593 <pre class="brush: asm; tab-size: 8">
 594         mov rsi, teststring
 595         call b_print_string
 596
 597         ...
 598
 599         teststring: db "This is a test string.", 0
 600 </pre>
 601 <br />
 602
 603
 604
 605 <h3>b_print_string_with_color</h3>
 606 <p><strong>Displays text with color</strong></p>
 607 <pre>
 608  IN:    RSI = message location (zero-terminated string)
 609         BL  = color
 610 OUT:    All registers perserved
 611 </pre>
 612 <p>The high 4 bits of BL is for the background color and the low 4 bits are for the text color. See the <a href="#colortable">Color Chart</a> in the Appendix.</p>
 613 <p>Example:</p>
 614 <pre class="brush: asm; tab-size: 8">
 615         mov rsi, colorteststring
 616         mov bl, 0x04                    ; Black background, Red text
 617         call b_print_string_with_color
 618
 619         ...
 620
 621         colorteststring: db "This is a test string in color!", 0
 622 </pre>
 623 <br />
 624
 625
 626
 627 <h3>b_print_char</h3>
 628 <p><strong>Displays a char</strong></p>
 629 <pre>
 630  IN:    AL  = char to display
 631 OUT:    All registers perserved
 632 </pre>
 633 <p>This function defaults to Light Gray text on a Black background</p>
 634 <p>Example:</p>
 635 <pre class="brush: asm; tab-size: 8">
 636         mov al, 'B'
 637         call b_print_char
 638 </pre>
 639 <br />
 640
 641
 642
 643 <h3>b_print_char_with_color</h3>
 644 <p><strong>Displays a char with color</strong></p>
 645 <pre>
 646  IN:    AL  = char to display
 647         BL  = color
 648 OUT:    All registers perserved
 649 </pre>
 650 <p>The high 4 bits of BL is for the background color and the low 4 bits are for the text color. See the <a href="#colortable">Color Chart</a> in the Appendix.</p>
 651 <p>Example:</p>
 652 <pre class="brush: asm; tab-size: 8">
 653         mov al, 'B'
 654         mov bl, 0x4F                    ; Red background, White text
 655         call b_print_char_with_color
 656 </pre>
 657 <br />
 658
 659
 660
 661 <h3>b_print_char_hex</h3>
 662 <p><strong>Displays a char in hex mode</strong></p>
 663 <pre>
 664  IN:    AL  = char to display
 665 OUT:    All registers perserved
 666 </pre>
 667 <p>Example:</p>
 668 <pre class="brush: asm; tab-size: 8">
 669         mov al, 0x5f
 670         call b_print_char_hex           ; "5F" will be printed
 671         mov al, 154
 672         call b_print_char_hex           ; "9A" will be printed
 673 </pre>
 674 <br />
 675
 676
 677
 678 <h3>b_print_char_hex_with_color</h3>
 679 <p><strong>Displays a char in hex mode</strong></p>
 680 <p>The high 4 bits of BL is for the background color and the low 4 bits are for the text color. See the <a href="#colortable">Color Chart</a> in the Appendix.</p>
 681 <pre>
 682  IN:    AL  = char to display
 683         BL  = color
 684 OUT:    All registers perserved
 685 </pre>
 686 <p>Example:</p>
 687 <pre class="brush: asm; tab-size: 8">
 688         mov al, 0x5f
 689         mov bl, 0x4F                    ; Red background, White text
 690         call b_print_char_hex           ; "5F" will be printed
 691         mov al, 154
 692         mov bl, 0x4F                    ; Red background, White text
 693         call b_print_char_hex           ; "9A" will be printed
 694 </pre>
 695 <br />
 696
 697
 698
 699 <h3>b_scroll_screen</h3>
 700 <p><strong>Scrolls the screen up by one line</strong></p>
 701 <pre>
 702  IN:    Nothing
 703 OUT:    All registers perserved
 704 </pre>
 705 <p>Example:</p>
 706 <pre class="brush: asm; tab-size: 8">
 707         call b_scroll_screen
 708 </pre>
 709 <br />
 710
 711
 712
 713 <h3>b_hide_cursor</h3>
 714 <p><strong>Turns off cursor in text mode</strong></p>
 715 <pre>
 716  IN:    Nothing
 717 OUT:    All registers perserved
 718 </pre>
 719 <p>Example:</p>
 720 <pre class="brush: asm; tab-size: 8">
 721         call b_hide_cursor
 722 </pre>
 723 <br />
 724
 725
 726
 727 <h3>b_show_cursor</h3>
 728 <p><strong>Turns on cursor in text mode</strong></p>
 729 <pre>
 730  IN:    Nothing
 731 OUT:    All registers perserved
 732 </pre>
 733 <p>Example:</p>
 734 <pre class="brush: asm; tab-size: 8">
 735         call b_show_cursor
 736 </pre>
 737 <br />
 738
 739
 740
 741
 742
 743 <hr noshade="noshade" style="width:80%;"></hr>
 744 <a name="serial"></a>
 745 <h2>Serial</h2>
 746 <p></p>
 747
 748
 749
 750 <h3>b_serial_send</h3>
 751 <p><strong>Send a byte over the primary serial port</strong></p>
 752 <pre>
 753  IN:    AL  = Byte to send over serial port
 754 OUT:    All registers preserved
 755 </pre>
 756 <p>Example:</p>
 757 <pre class="brush: asm; tab-size: 8">
 758         mov al, 'H'
 759         call b_serial_send
 760 </pre>
 761 <br />
 762
 763
 764
 765 <h3>b_serial_recv</h3>
 766 <p><strong>Receive a byte from the primary serial port</strong></p>
 767 <pre>
 768  IN:    Nothing
 769 OUT:    AL  = Byte recevied
 770         Carry flag is set if a byte was received, otherwise AL is trashed
 771         All other registers preserved
 772 </pre>
 773 <p>Example:</p>
 774 <pre class="brush: asm; tab-size: 8">
 775         call b_serial_recv
 776         jnc gotnothing
 777 </pre>
 778 <br />
 779
 780
 781
 782
 783
 784 <hr noshade="noshade" style="width:80%;"></hr>
 785 <a name="smp"></a>
 786 <h2>Symmetric Multiprocessing (SMP)</h2>
 787 <p></p>
 788
 789
 790
 791 <h3>b_smp_reset</h3>
 792 <p><strong>Resets a CPU/Core</strong></p>
 793 <pre>
 794  IN:    AL = CPU APIC ID #
 795 OUT:    Nothing. All registers preserved.
 796 </pre>
 797 <p>This function resets an AP to run the ap_clear kernel code.</p>
 798 <p>Example:</p>
 799 <pre class="brush: asm; tab-size: 8">
 800         mov al, 0x01                    ; Select CPU Core with APIC ID 1
 801         call b_smp_reset                ; Reset the CPU Core
 802 </pre>
 803 <br />
 804
 805
 806
 807 <h3>b_smp_get_id</h3>
 808 <p><strong>Returns the APIC ID of the CPU that ran this function</strong></p>
 809 <pre>
 810  IN:    Nothing
 811 OUT:    RAX = CPU's APIC ID number
 812         All other registers perserved
 813 </pre>
 814 <p>Example:</p>
 815 <pre class="brush: asm; tab-size: 8">
 816         call b_smp_get_id               ; APIC ID returned in AL
 817 </pre>
 818 <br />
 819
 820
 821
 822 <h3>b_smp_enqueue</h3>
 823 <p><strong>Add a workload to the processing queue</strong></p>
 824 <pre>
 825  IN:    RAX = Code to execute
 826 OUT:    Carry set on failure (Queue full)
 827         All other registers perserved
 828 </pre>
 829 <p>This function adds a workload to the processing queue of the system. All available CPU Cores actively poll this queue and will automatically execute b_smp_dequeue.</p>
 830 <p>Example:</p>
 831 <pre class="brush: asm; tab-size: 8">
 832         mov rax, ap_print_id            ; Our code to run on all CPUs
 833         mov rcx, 64                     ; Number of instances to spawn
 834
 835 spawn:
 836         call b_smp_enqueue
 837         sub rcx, 1
 838         cmp rcx, 0
 839         jne spawn
 840 </pre>
 841 <br />
 842
 843
 844
 845 <h3>b_smp_dequeue</h3>
 846 <p><strong>Dequeue a workload from the processing queue</strong></p>
 847 <pre>
 848  IN:    Nothing
 849 OUT:    RAX = Code to execute (Set to 0 if queue was empty)
 850         All other registers perserved
 851 </pre>
 852 <p>This function is automatically called by each CPU Core that is in the Idle Kernel loop. It is also useful for the BSP to call this function after adding the initial workloads to the queue.</p>
 853 <p>Example:</p>
 854 <pre class="brush: asm; tab-size: 8">
 855 bsp:
 856         call b_smp_dequeue              ; Try to dequeue a workload
 857         jc emptyqueue                   ; If carry is set then the queue is empty
 858         call rax                        ; Otherwise run the workload
 859         call b_smp_queuelen             ; Check the length of the queue
 860         cmp rax, 0
 861         jne bsp                         ; If it is not empty try to do another workload
 862 </pre>
 863 <br />
 864
 865
 866
 867 <h3>b_smp_run</h3>
 868 <p><strong>Call the code address stored in RAX</strong></p>
 869 <pre>
 870  IN:    RAX = Address of code to execute
 871 OUT:    Nothing
 872 </pre>
 873 <p>Needed for compatibilty with C.</p>
 874 <p>Example:</p>
 875 <pre class="brush: asm; tab-size: 8">
 876         call b_smp_dequeue
 877         call b_smp_run                  ; You could also use "call rax" here
 878 </pre>
 879 <br />
 880
 881
 882
 883 <h3>b_smp_queuelen</h3>
 884 <p><strong>Returns the number of items in the processing queue</strong></p>
 885 <pre>
 886  IN:    Nothing
 887 OUT:    RAX = number of items in processing queue
 888 </pre>
 889 <p>b_smp_dequeue makes use of this function.</p>
 890 <p>Example:</p>
 891 <pre class="brush: asm; tab-size: 8">
 892         call b_smp_queuelen             ; Check the length of the queue
 893         cmp rax, 0
 894         je queue_empty
 895 </pre>
 896 <br />
 897
 898
 899
 900 <h3>b_smp_wait</h3>
 901 <p><strong>Wait until all other CPU Cores are finished processing</strong></p>
 902 <pre>
 903  IN:    Nothing
 904 OUT:    All registers preserved
 905 </pre>
 906 <p>Use this function to wait until all available CPU Cores are finished processing.</p>
 907 <p>Example:</p>
 908 <pre class="brush: asm; tab-size: 8">
 909         call b_smp_wait                 ; Wait for all other processors to finish
 910 </pre>
 911 <br />
 912
 913
 914
 915 <h3>b_smp_lock</h3>
 916 <p><strong>Attempt to lock a mutex</strong></p>
 917 <pre>
 918  IN:    RAX = Address of lock variable
 919 OUT:    Nothing. All registers preserved.
 920 </pre>
 921 <p>Attempt to lock a mutex. This function will block until the mutex can be locked.</p>
 922 <p>Example:</p>
 923 <pre class="brush: asm; tab-size: 8">
 924         mov rax, Mutex
 925         call b_smp_lock                 ; Attempt to lock the mutex
 926 </pre>
 927 <br />
 928
 929
 930
 931 <h3>b_smp_unlock</h3>
 932 <p><strong>Unlock a mutex</strong></p>
 933 <pre>
 934  IN:    RAX = Address of lock variable
 935 OUT:    Nothing. All registers preserved.
 936 </pre>
 937 <p>Unlock a mutex.</p>
 938 <p>Example:</p>
 939 <pre class="brush: asm; tab-size: 8">
 940         mov rax, Mutex
 941         call b_smp_unlock               ; Unlock the mutex
 942 </pre>
 943 <br />
 944
 945
 946
 947 <h3>b_smp_numcores</h3>
 948 <p><strong>Returns the number of cores in this computer</strong></p>
 949 <pre>
 950  IN:    RAX = Address of lock variable
 951 OUT:    Nothing. All registers preserved.
 952 </pre>
 953 <p>Example:</p>
 954 <pre class="brush: asm; tab-size: 8">
 955         call b_smp_numcores
 956 </pre>
 957 <br />
 958
 959
 960
 961
 962
 963 <hr noshade="noshade" style="width:80%;"></hr>
 964 <a name="sound"></a>
 965 <h2>Sound</h2>
 966 <p></p>
 967
 968
 969
 970 <h3>b_speaker_tone</h3>
 971 <p><strong>Generate a tone on the PC speaker</strong></p>
 972 <pre>
 973  IN:    RAX = note frequency
 974 OUT:    All registers preserved
 975 </pre>
 976 <p>Call b_speaker_off to stop the tone</p>
 977 <p>Example:</p>
 978 <pre class="brush: asm; tab-size: 8">
 979         mov rax, 4000                   ; A 'C' note
 980         call b_speaker_tone
 981 </pre>
 982 <br />
 983
 984
 985
 986 <h3>b_speaker_off</h3>
 987 <p><strong>Turn off PC speaker</strong></p>
 988 <pre>
 989  IN:    Nothing
 990 OUT:    All registers preserved
 991 </pre>
 992 <p>Example:</p>
 993 <pre class="brush: asm; tab-size: 8">
 994         call b_speaker_off
 995 </pre>
 996 <br />
 997
 998
 999
1000 <h3>b_speaker_beep</h3>
1001 <p><strong>Create a standard OS beep</strong></p>
1002 <pre>
1003  IN:    Nothing
1004 OUT:    All registers preserved
1005 </pre>
1006 <p>Example:</p>
1007 <pre class="brush: asm; tab-size: 8">
1008         call b_speaker_beep
1009 </pre>
1010 <br />
1011
1012
1013
1014
1015
1016 <hr noshade="noshade" style="width:80%;"></hr>
1017 <a name="string"></a>
1018 <h2>String</h2>
1019 <p></p>
1020
1021
1022
1023 <h3>b_int_to_string</h3>
1024 <p><strong>Convert a binary interger into an string</strong></p>
1025 <pre>
1026  IN:    RAX = binary integer
1027         RDI = location to store string
1028 OUT:    RDI = points to end of string
1029         All other registers preserved
1030 </pre>
1031 <p>The minimum return value is 0 and maximum return value is 18446744073709551615. The destination string needs to be able to store at least 21 characters (20 for the digits and 1 for the string terminator).</p>
1032 <p>Example:</p>
1033 <pre class="brush: asm; tab-size: 8">
1034         mov rax, 0xFFFFFFFFFFFFFFFF
1035         mov rdi, teststring
1036         mov rsi, rdi                    ; Set RSI for print_string call
1037         call b_int_to_string
1038         call b_print_string             ; "18446744073709551615" will be printed
1039
1040         ...
1041
1042         teststring: times 21 db 0       ; Space for a 20 character string
1043 </pre>
1044 <br />
1045
1046
1047
1048 <h3>b_string_to_int</h3>
1049 <p><strong>Convert a string into a binary interger</strong></p>
1050 <pre>
1051  IN:    RSI = location of string
1052 OUT:    RAX = integer value
1053         All other registers preserved
1054 </pre>
1055 <p>Example:</p>
1056 <pre class="brush: asm; tab-size: 8">
1057         mov rsi, teststring
1058         call b_string_to_int            ; RAX will be set to the decimal value 460341242
1059
1060         ...
1061
1062         teststring: db "460341242", 0
1063
1064 </pre>
1065 <br />
1066
1067
1068
1069 <h3>b_int_to_hex_string</h3>
1070 <p><strong>Convert an integer to a hex string</strong></p>
1071 <pre>
1072  IN:    RAX = Integer value
1073         RDI = Location to store string
1074 OUT:    All registers preserved
1075 </pre>
1076 <p>Example:</p>
1077 <pre class="brush: asm; tab-size: 8">
1078         mov rax, 3735928559
1079         mov rdi, teststring
1080         mov rsi, rdi                    ; Set RSI for print_string call
1081         call b_int_to_hex_string
1082         call b_print_string             ; "DEADBEEF" will be printed
1083
1084         ...
1085
1086         teststring: times 21 db 0       ; Space for a 20 character string
1087 </pre>
1088 <br />
1089
1090
1091
1092 <h3>b_hex_string_to_int</h3>
1093 <p><strong>Convert up to 8 hexascii to bin</strong></p>
1094 <pre>
1095  IN:    RSI = Location of hex asciiz string
1096 OUT:    RAX = Binary value of hex string
1097         All other registers preserved
1098 </pre>
1099 <p>Example:</p>
1100 <pre class="brush: asm; tab-size: 8">
1101         mov rsi, teststring
1102         call b_hex_string_to_int        ; RAX will be set to 4277006349
1103
1104         ...
1105
1106         teststring: db "FEEDF00D", 0
1107 </pre>
1108 <br />
1109
1110
1111
1112 <h3>b_string_length</h3>
1113 <p><strong>Return length of a string</strong></p>
1114 <pre>
1115  IN:    RSI = string location
1116 OUT:    RCX = length (not including the NULL terminator)
1117         All other registers preserved
1118 </pre>
1119 <p>Example:</p>
1120 <pre class="brush: asm; tab-size: 8">
1121         mov rsi, teststring
1122         call b_string_length            ; RCX will be set to 45
1123
1124         ...
1125
1126         teststring: db "This is a test of the string length function!", 0
1127 </pre>
1128 <br />
1129
1130
1131
1132 <h3>b_find_char_in_string</h3>
1133 <p><strong>Find first location of character in a string</strong></p>
1134 <pre>
1135  IN:    RSI = string location
1136         AL  = character to find
1137 OUT:    RAX = location in string, or 0 if char not present
1138         All other registers preserved
1139 </pre>
1140 <p>Example:</p>
1141 <pre class="brush: asm; tab-size: 8">
1142         mov rsi, teststring
1143         mov al, 'a'
1144         call b_find_char_in_string      ; RAX will be set to 26 (The 'a' in 'lowercase' is the first instance)
1145
1146         ...
1147
1148         teststring: db "Where is the first lowercase 'a'?", 0
1149 </pre>
1150 <br />
1151
1152
1153
1154 <h3>b_string_charchange</h3>
1155 <p><strong>Change all instances of a character in a string</strong></p>
1156 <pre>
1157  IN:    RSI = string location
1158         AL  = character to replace
1159         BL  = replacement character
1160 OUT:    All registers preserved
1161 </pre>
1162 <p>Example:</p>
1163 <pre class="brush: asm; tab-size: 8">
1164         mov rsi, teststring
1165         mov al, 'e'
1166         mov bl, 'A'
1167         call b_string_charchange
1168         call b_print_string             ; "PlAasA rAplacA thA lowArcasA lAttAr E's." will be printed
1169
1170         ...
1171
1172         teststring: db "Please replace the lowercase letter E's.", 0
1173 </pre>
1174 <br />
1175
1176
1177
1178 <h3>b_string_copy</h3>
1179 <p><strong>Copy the contents of one string into another</strong></p>
1180 <pre>
1181  IN:    RSI = source
1182         RDI = destination
1183 OUT:    All registers preserved
1184 </pre>
1185 <p>It is up to the programmer to ensure that there is sufficient space in the destination!</p>
1186 <p>Example:</p>
1187 <pre class="brush: asm; tab-size: 8">
1188         mov rsi, srcstring
1189         mov rdi, deststring
1190         call b_string_copy
1191         mov rsi, deststring
1192         call b_print_string             ; "Copy this string!" will be printed
1193
1194         ...
1195
1196         srcstring: "Copy this string!", 0
1197         deststring: times 21 db 0       ; Space for a 20 character string
1198 </pre>
1199 <br />
1200
1201
1202
1203 <h3>b_string_truncate</h3>
1204 <p><strong>Chop string down to specified number of characters</strong></p>
1205 <pre>
1206  IN:    RSI = string location
1207         RAX = number of characters
1208 OUT:    All registers preserved
1209 </pre>
1210 <p>Example:</p>
1211 <pre class="brush: asm; tab-size: 8">
1212         mov rsi, teststring
1213         mov rax, 5
1214         call b_string_truncate
1215         call b_print_string             ; "AaBbC" will be printed on screen
1216
1217         ...
1218
1219         teststring: db "AaBbCcDd 123", 0
1220 </pre>
1221 <br />
1222
1223
1224
1225 <h3>b_string_join</h3>
1226 <p><strong>Join two strings into a third string</strong></p>
1227 <pre>
1228  IN:    RAX = string one
1229         RBX = string two
1230         RDI = destination string
1231 OUT:    All registers preserved
1232 </pre>
1233 <p>Example:</p>
1234 <pre class="brush: asm; tab-size: 8">
1235         mov rax, string1
1236         mov rbx, string2
1237         mov rdi, deststring
1238         call b_string_join
1239         mov rsi, deststring
1240         call b_print_string             ; "AAAAABBBBB" will be printed
1241
1242         ...
1243
1244         string1: "AAAAA", 0
1245         string2: "BBBBB", 0
1246         deststring: times 41 db 0       ; Space for a 40 character string
1247 </pre>
1248 <br />
1249
1250
1251
1252 <h3>b_string_chomp</h3>
1253 <p><strong>Strip leading and trailing spaces from a string</strong></p>
1254 <pre>
1255  IN:    RSI = string location
1256 OUT:    All registers preserved
1257 </pre>
1258 <p>Example:</p>
1259 <pre class="brush: asm; tab-size: 8">
1260         mov rsi, teststring
1261         call b_string_chomp
1262         call b_print_string             ; "This is a test." will be printed
1263
1264         ...
1265
1266         teststring: db "  This is a test.       ", 0
1267 </pre>
1268 </pre>
1269 <br />
1270
1271
1272
1273 <h3>b_string_strip</h3>
1274 <p><strong>Removes specified character from a string</strong></p>
1275 <pre>
1276  IN:    RSI = string location
1277         AL  = character to remove
1278 OUT:    All registers preserved
1279 </pre>
1280 <p>Example:</p>
1281 <pre class="brush: asm; tab-size: 8">
1282         mov rsi, teststring
1283         mov al, 'i'
1284         call b_string_strip
1285         call b_print_string             ; "Ths s a test of the strng_strp functon." will be printed
1286
1287         ...
1288
1289         teststring: db "This is a test of the string_strip function.", 0
1290 </pre>
1291 <br />
1292
1293
1294
1295 <h3>b_string_compare</h3>
1296 <p><strong>See if two strings match</strong></p>
1297 <pre>
1298  IN:    RSI = string one
1299         RDI = string two
1300 OUT:    Carry flag set if same
1301 </pre>
1302 <p>Example:</p>
1303 <pre class="brush: asm; tab-size: 8">
1304         mov rsi, string1
1305         mov rdi, string2
1306         call b_string_compare
1307         jc string_equal
1308         ; Falls through to here if strings are not equal
1309
1310         ...
1311
1312         string1: "AAAAA", 0
1313         string2: "BBBBB", 0
1314 </pre>
1315 <br />
1316
1317
1318
1319 <h3>b_string_uppercase</h3>
1320 <p><strong>Convert zero-terminated string to uppercase</strong></p>
1321 <pre>
1322  IN:    RSI = string location
1323 OUT:    All registers preserved
1324 </pre>
1325 <p>Example:</p>
1326 <pre class="brush: asm; tab-size: 8">
1327         mov rsi, teststring
1328         call b_string_uppercase
1329         call b_print_string             ; "AABBCCDD 123" will be printed
1330
1331         ...
1332
1333         teststring: db "AaBbCcDd 123", 0
1334 </pre>
1335 <br />
1336
1337
1338
1339 <h3>b_string_lowercase</h3>
1340 <p><strong>Convert zero-terminated string to lowercase</strong></p>
1341 <pre>
1342  IN:    RSI = string location
1343 OUT:    All registers preserved
1344 </pre>
1345 <p>Example:</p>
1346 <pre class="brush: asm; tab-size: 8">
1347         mov rsi, teststring
1348         call b_string_lowercase
1349         call b_print_string             ; "aabbccdd 123" will be printed
1350
1351         ...
1352
1353         teststring: db "AaBbCcDd 123", 0
1354 </pre>
1355 <br />
1356
1357
1358
1359 <h3>b_get_time_string</h3>
1360 <p><strong>Store the current time in a string in format "HH:MM:SS"</strong></p>
1361 <pre>
1362  IN:    RDI = location to store string (must be able to fit 9 bytes, 8 data plus null terminator)
1363 OUT:    All registers preserved
1364 </pre>
1365 <p>Example:</p>
1366 <pre class="brush: asm; tab-size: 8">
1367         mov rdi, temp_string
1368         call b_get_time_string          ; temp_string will be set to "16:45:20" if that was the current time
1369
1370         ...
1371
1372         temp_string: times 41 db 0      ; Space for a 40 character string
1373 </pre>
1374 <br />
1375
1376
1377
1378 <h3>b_get_date_string</h3>
1379 <p><strong>Store the current time in a string in format "YYYY/MM/DD"</strong></p>
1380 <pre>
1381  IN:    RDI = location to store string (must be able to fit 11 bytes, 10 data plus null terminator)
1382 OUT:    All registers preserved
1383 </pre>
1384 <p>Example:</p>
1385 <pre class="brush: asm; tab-size: 8">
1386         mov rdi, temp_string
1387         call b_get_date_string          ; temp_string will be set to "2010/04/27" if that was the current date
1388
1389         ...
1390
1391         temp_string: times 41 db 0      ; Space for a 40 character string
1392 </pre>
1393 <br />
1394
1395
1396
1397 <h3>b_is_digit</h3>
1398 <p><strong>Check if character is a digit</strong></p>
1399 <pre>
1400  IN:    AL  = ASCII char
1401 OUT:    EQ flag set if numeric
1402 </pre>
1403 <p>JE (Jump if Equal) or JNE (Jump if Not Equal) can be used after this function is called.</p>
1404 <p>Example:</p>
1405 <pre class="brush: asm; tab-size: 8">
1406         mov al, '6'
1407         call b_is_digit
1408         je itsanumber                   ; Jump if it was a digit, else fall through to next instruction
1409         mov rbx, 2134
1410 </pre>
1411 <br />
1412
1413
1414
1415 <h3>b_is_alpha</h3>
1416 <p><strong>Check if character is a letter</strong></p>
1417 <pre>
1418  IN:    AL  = ASCII char
1419 OUT:    EQ flag set if alpha
1420 </pre>
1421 <p>JE (Jump if Equal) or JNE (Jump if Not Equal) can be used after this function is called.</p>
1422 <p>Example:</p>
1423 <pre class="brush: asm; tab-size: 8">
1424         mov al, 'j'
1425         call b_is_alpha
1426         jne notaletter                  ; Jump if it was not a letter, else fall through to next instruction
1427         mov rbx, 2134
1428 </pre>
1429 <br />
1430
1431
1432
1433 <h3>b_string_parse</h3>
1434 <p><strong>Parse a string into individual words</strong></p>
1435 <pre>
1436  IN:    RSI = Address of string
1437 OUT:    RCX = word count
1438 </pre>
1439 <p>This function will remove extra whitespace in the source string and also return the word count. "This is&nbsp;&nbsp; a test. " will update to "This is a test."</p>
1440 <p>Example:</p>
1441 <pre class="brush: asm; tab-size: 8">
1442         mov rsi, teststring
1443         call b_string_parse
1444         call b_print_string             ; "This is a test." will be printed. Also RCX will be set to 4
1445
1446         ...
1447
1448         teststring: db "This   is  a test. ", 0
1449 </pre>
1450 <br />
1451
1452
1453
1454 <h3>b_string_append</h3>
1455 <p><strong>Append a string to an existing string</strong></p>
1456 <pre>
1457  IN:    RSI = String to be appended
1458         RDI = Destination string
1459 OUT:    All registers preserved
1460 </pre>
1461 <p>Note: It is up to the programmer to ensure that there is sufficient space in the destination</p>
1462 <p>Example:</p>
1463 <pre class="brush: asm; tab-size: 8">
1464         mov rsi, teststring1
1465         mov rdi, teststring2
1466         call b_string_append
1467         mov rsi, teststring2
1468         call b_print_string             ; "Test2Test1" will be printed.
1469
1470         ...
1471
1472         teststring1: db "Test1", 0
1473         teststring2: db "Test2", 0
1474 </pre>
1475 <br />
1476
1477
1478
1479
1480
1481 <hr noshade="noshade"></hr>
1482
1483
1484 <h2>Appendix</h2>
1485 <a name="appendix"></a>
1486
1487 <h3>Text mode color table:</h3>
1488 <a name="colortable"></a>
1489 <img src="images/Text Mode Color Table.png"></img>
1490 <p>For the b_print_string_with_color and b_print_char_with_color the color for the foreground (text) and background is selected with BL. A value of 0x09 in BL would give bright blue text on a black background. A value of 0xA4 would give you red text on a bright green background (yuck).</p>
1491
1492
1493 <br />
1494
1495
1496
1497
1498
1499 <hr noshade="noshade"></hr>
1500
1501
1502 <h2>Extra</h2>
1503
1504 <a name="license"></a>
1505 <h3>License</h3>
1506
1507 <p>BareMetal OS is open source and released under the 3-clause "New BSD License" (see <strong>docs/LICENSE.TXT</strong> in the BareMetal OS distribution). Essentially, it means you can do anything you like with the code, including basing your own project on it, providing you retain the license file and give credit to Return Infinity and the BareMetal OS developers for their work.</p>
1508
1509
1510 <br />
1511
1512
1513
1514 </div>
1515 </body>
1516 </html>
1517